{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# DataGeometry objects (`geo`)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The DataGeometry object is the hypertools data object class. A `geo` contains the data, figure handles, and transform functions used to create a plot. Note that this class should not be called directly, but is used by the hyp.plot function to create a plot object.\n",
    "\n",
    "In this tutorial we will explore the features of a geo and how it may be used."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Import Hypertools"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import hypertools as hyp\n",
    "import seaborn as sb\n",
    "\n",
    "%matplotlib inline"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Load your data"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In this case, we have used one of the sample datasets built into the package."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "geo = hyp.load('mushrooms')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Plot it"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can plot a `geo` by calling the plot method"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "geo.plot()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Exploring the geo"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Hypertools version"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The version field contains the version number of hypertools that the geo was generated with."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "geo.version"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Data and plot"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The data field contains the raw data."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "geo.data.head()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Transformed data"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The `xform_data` field contains the data that have been transformed according to the user-specified normalize, reduce, and align options (in this case, the data was automatically reduced to 3 dimensions for plotting when we called `hyp.plot`)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "geo.xform_data"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Normalize, reduce and align metadata"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The `reduce`, `align` and `normalize` fields contain information about the model and parameters used in each of the  analyses. \n",
    "\n",
    "The reduce and align fields contain dictionaries with the model information and the normalize field contains a string."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "print(geo.normalize)\n",
    "print(geo.reduce)\n",
    "print(geo.align)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Plotting axes and animations"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The `ax` and `line_ani` fields hold the plot axes and the animation setting (in this case None) for plotting, respectively.\n",
    "\n",
    "To read more about the plot axes and line animation objects and their utility, see the matlplotlib documentation for [axes](http://matplotlib.org/api/axes_api.html) and [animations](http://matplotlib.org/api/animation_api.html), respectively."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "geo.ax"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "geo.line_ani"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Plotting with geos"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You can also generate a new plot (a new geo) from data stored in the geo using geo.plot.\n",
    "\n",
    "This plotting feature accepts all of the keyword arguments supported by hypertools.plot.\n",
    "\n",
    "First, let's plot without making any changes."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "geo.plot()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now, let's change the plot using some keyword arguments.\n",
    "\n",
    "In the example below, the data are re-transformed using all of the same options as in the original plot, but with the number of dimensions specified by the reduce model set to 2."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "geo.plot(ndims = 2)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Tranforming data using geos"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "An additional feature afforded by geos is the ability to later analyze other datasets using the same transformations performed on the original data in the geo. That is, whatever normalization, alignment, and reduction parameters were used on the original data in the geo can be quickly and easily applied to any new dataset using a single line of code! \n",
    "\n",
    "\n",
    "This allows for easy comparison of multiple datasets. Here, we load a built in dataset (the weights dataset) and apply the transform from the geo data to the first element of weights."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "weights = hyp.load('weights_avg').get_data()\n",
    "transformed = geo.transform(weights)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can use heatmaps to visualized an element of the new data before and after it has been transformed by the same means as the geo data."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "ax = sb.heatmap(weights[0])"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "ax = sb.heatmap(transformed[0])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Saving geos"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You can also easily save a geo using geo.save. The geo will save as a 'geo' file, which is a dictionary containing the elements of a data geometry object saved in the hd5 format using deepdish.\n",
    "\n",
    "To specify the compression type, pass a string to the compression argument, as below.  See the deepdish documentation for the full list of compression options: http://deepdish.readthedocs.io/en/latest/api_io.html#deepdish.io.save"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "# geo.save('MyGeoFile')\n",
    "# geo.save('MyGeoFile', compression = 'blosc')"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.6.1"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}
